home *** CD-ROM | disk | FTP | other *** search
/ IRIX 6.5 Applications 1999 May / SGI IRIX 6.5 Applications 1999 May.iso / dist / extras / netscape_lite.idb / usr / share / src / ns_plugin / README.z / README
Encoding:
Text File  |  1999-03-15  |  5.9 KB  |  134 lines
  1. ----------------------------------------------------------------------
  2. Netscape Navigator Unix Plugin Architecture V 0.6
  3. ----------------------------------------------------------------------
  4. dpSuresh <dp@netscape.com>
  5. Tue Jan 16 20:37:24 PST 1996
  6.  
  7. This document describes the architecture of the unix plugins.
  8. This would help developers write their own plugins and interface them
  9. with netscape.
  10.  
  11. Intended Audience
  12. ----------------------------------------------------------------------
  13.     - Plugin developers on unix platforms
  14. This assumes that the developer is aware of when and why a plugin is
  15. required.
  16.  
  17. Platforms currently supported
  18. ----------------------------------------------------------------------
  19.     - SunOS 4.1.3 and above
  20.     - Solaris 5.3
  21.     - Solaris 5.4
  22.     - IRIX 5.2 and above
  23.     - OSF1 V2.0 alpha and above
  24.  
  25. Contents
  26. ----------------------------------------------------------------------
  27.     - General architecture of Netscape Unix Plugins
  28.     - How to write a plugin
  29.     - Sample Text plugin
  30.     - Do's and Dont's
  31.  
  32. General architecture of Netscape Unix Plugins
  33. ----------------------------------------------------------------------
  34.  
  35. ----------------------------------------------------------------------
  36.                |                         |
  37.                |                         |
  38. Netscape       |         Wrapper         |             Plugin Developer
  39. Navigator      |         npunix.c        |             npshell.c
  40.                |                         |
  41. Talks with the | Implements function     |  Can ignore the existence of
  42. the plugin via | tables as required      |  functions tables and call NPN_*()
  43. wrapper code   | by the navigator's      |  functions to call the navigator
  44. in npnix.c     | plugin interface and    |  and implement NPP_* functions
  45.                | provides plugin         |  to hookup to the navigator.
  46.                | developers with a       |
  47.                | std. set of functions   |
  48.                |                         |
  49.                | WONT NEED TO EDIT THIS. | FILL UP functions in npshell.c
  50.                | NEED TO COMPILER WITH   | and write many more...
  51.                | THIS.                   |
  52. ----------------------------------------------------------------------
  53.  
  54. The plugin in the unix platform is implemented as a dynamically loadable
  55. module (.so) The navigator searches for these dynamically loadable modules
  56. in the list of directories as specified by the environment variable
  57. NPX_PLUGIN_PATH. This variable can be set to a ':' separated list of
  58. directories. The default path if this environment variable is not set
  59. is "/var/netscape/communicator/plugins"
  60.  
  61.     NOTE: On SunOS4.1.3, if there are any non-loadable modules in
  62.           any of the directories specified by NPX_PLUGIN_PATH, then
  63.           the dlopen() library call exits rather than giving an error.
  64.           thus causing the navigator to terminate.
  65.  
  66. The navigator detect which MIME types are recognized by a plugin by calling
  67. NPP_GetMIMEDescription() in npshell.c (via NP_GetMIMEDescription() in
  68. npunix.c). From then on, whenever it detect data of the
  69. particular MIME type, it loads the plugin and creates instances of the
  70. corresponding plugin object. Before creating the first plugin instance
  71. the navigator will call NPP_Initialize() in npshell.c (via NP_Initialize()
  72. in npunix.c). Also after the last plugin instance has been destroyed,
  73. the navigator will call NPP_Shutdown() in npshell.c (via NP_Shutdown()
  74. in npunix.c)
  75.  
  76. How to write a plugin
  77. ----------------------------------------------------------------------
  78.     1. Fill up all the neccessary functions in npshell.c
  79.        To hook up and talk with the navigator. Refer to
  80.        "The plugin API" for more information on these
  81.        functions.
  82.  
  83.     2. Add new functions/files as required by your plugin.
  84.        Use npapi.h for a description of data structures passed
  85.        between the navigator and the plugin code.
  86.  
  87.     3. Compile the plugin code with npunix.c, npshell.c into
  88.        a platform specific dynamically loadable module.
  89.  
  90.     4. Install the dynamically loadable in NPX_PLUGIN_PATH,
  91.        /var/netscape/communicator/plugins/ by default.
  92.  
  93.     5. Start the navigator. From now on, whenever the MIME type
  94.        of interest to the plugin is encountered, the navigator
  95.        will call the apropriate functions in the plugin.
  96.  
  97. Sample Text plugin
  98. ----------------------------------------------------------------------
  99. As an example, here is a text plugin. This plugin is intended only to
  100. demonstrate how plugin developers can write plugins. The text plugin
  101. operates on MIME type and extension "application/x-data;.txt"
  102. So whenever the navigator gets data with mime type "application/x-data"
  103. (or) needs to display a file with the extension ".txt", it passes the
  104. data over to the plugin code as discussed by the Plugin API. The text
  105. plugin creates a scrolled window using motif and displays the data
  106. it received in the window. All code that is specific to the text
  107. plugin is ifdeffed TEXT_PLUGIN in npshell.c
  108.  
  109. Do's and Dont's
  110. ----------------------------------------------------------------------
  111.     - INSTALL YOUR OWN EVENT HANDLERS FOR THE PLUGIN WINDOW TO
  112.       GET EVENTS.
  113.       Netscape Navigator uses Xt/Motif for its display. Plugins
  114.       can use them and install their own event handlers for their
  115.       window.
  116.  
  117.     - DONT USE WorkProcs IN Xt.
  118.       WorkProcs will not be called.
  119.  
  120.     - USE THE X RESOURCE NAME SPACE WITH CARE.
  121.       plugins and netscape share the same X resources space.
  122.       So be sure your plugin gets it resources separately.
  123.       The navigator resources do not follow a pattern although
  124.       we eventually will. Until then, chose unique names that
  125.       are not used by the navigator for its X resources for
  126.       X resources and names of widgets used by plugins.
  127.  
  128.     - TAKE CARE WHEN INSTALLING TIMERS TO GET IDLE CYCLES.
  129.       Plugins installing TIMERS to get idle cycles (e.g for doing
  130.       some animation as long as the plugin is in view) by using the
  131.       XtAppAddTimeOut() should take care to not install 0 interval
  132.       timer callbacks. If they do, then the network events will never
  133.       happen.
  134.